Magnum One/Magnum One (Mid-American Digital) (Disc Manufacturing).iso/d3/multibak.arc/MULTIBAK.DOC

Text File | 1989-10-24 | 19KB | 418 lines

             MULTIBAK: A Multiple Generation File Backup Utility

                        Copyright 1989 Gilbert Shapiro

                                  **********


                                  I. Purpose

Many microcomputer programs that modify files, such as word processors, data
base managers, and spreadsheets, provide for a single generation of backup,
usually renaming the old version of "filename.ext" to "filename.bak" before
writing a new "filename.ext" to disk. When a new revision is again saved, the
old version again becomes "filename.bak," wiping out the backup file saved
earlier.  This is not always satisfactory. We may change our minds about a
major change later, and want to return the document or the spreadsheet to its
state several generations earlier. We may even discover much later a major
error and the loss of earlier versions could seriously set our work back. For
these reasons, some mainframe operating systems provide the option of multiple
generations of backup.  Not only the previous version of a file, but as many
generations as the user wishes (or as many as can fit in his disk space) can
be preserved. MULTIBAK is a set of programs intended to provide the most
important features of such mainframe services for MSDOS systems.

Any computer work that creates multiple changes in files can be made less
frustrating and safer from disaster by using this collection of programs.
When editing a document or developing a spreadsheet, for example, one might
create a backup almost at the stroke of a key whenever significant changes are
made, accumulating them until a final version is completed and verified. The
backup files can then be conveniently erased using the PURGE program provided.



                         II. Versions of MULTIBAK

This is the freely distributed version of MULTIBAK.  You are invited to  make
as many copies of this program as you wish for your own use or the use of
others, for non-commercial purposes. You may not, however, charge anything for
MULTIBAK (except for user groups, who may charge a cost-based fee, not to
exceed $10, to cover their own costs).

The free version of MULTIBAK consists of the following files:

    MULTIBAK.DOC    This file.
    MBC.EXE         The COPY model of MULTIBAK.
    MBR.EXE         The RENAME model of MULTIBAK.
    PURGE.EXE       A program for conveniently and safely erasing backup files.

These programs comprise a fully functional system that will be sufficient for
many users.  A more elaborate system, with additional conveniences, is
also available. If you send $20 to:

    CN Software, Dept. 190
    414 S. Craig St., Suite 280
    Pittsburgh, PA 15213

as a registered user of MULTIBAK you will receive a copy of an enhanced
system, which includes

    1. MEMORY RESIDENT versions of both the COPY and RENAME models. These make
        MULTIBAK available to the user at the touch of a Hot Key of his choice,
        permitting execution from within programs that do not provide
        facilities for the execution of DOS commands.

    2. Two additional utilities: REVERT, which quickly and simply returns you to
        an earlier version of your file while preserving the current version,
        and RENUMBER, a facility to change a broken series of backup names to
        an unbroken series beginning at number one.


                      III. General Functions of MULTIBAK

MULTIBAK saves the current version of a file under a new file name; it is
normally called immediately prior to issuing a "save" command to some program,
such as a word processor, to write a new version.  The name of the backup file
is, by default, provided by MULTIBAK.  Unless over-ridden by the user, by means
described below, it is constructed as follows:

     - The drive, directory, and first file name are identical with the
       original file.
     - The extension is the first character of the extension of the original
       file, followed by the lowest integer from 1 to 99 not yet used in
       backup versions of that file. If  the original file has no extension,
       the backup file extension will begin with a dash:  for example, the first
       backup of MYFILE.  will be MYFILE.-1, the second MYFILE.-2.

Thus, if the file to be backed up is MYFILE.EXT, the first call to MULTIBAK
will produce a backup file named MYFILE.E1, the second backup will be called
MYFILE.E2, and so on.  If, after the call to MULTIBAK, a new version is saved
by a spreadsheet or word processor, it can always have the original name,
MYFILE.EXT. Note that the preservation of the first letter of the original
extension permits us to distinguish the backups of MYPROG.C, MYPROG.EXE and
MYPROG.DOC, which will, respectively, have extensions beginning with C, E, and
D. (The backups of MYFILE.BAS, MYFILE.BAT, and MYFILE.BAK will be jumbled
together, however.)

The COPY model, MBC.EXE, creates a new backup file by copying the current
version, without disturbing the original.  The RENAME model, MBR.EXE, on the
other hand, calls upon DOS to rename the original, changing the name in
the directory. Generally, these two procedures behave like the DOS commands
with the same names, but with one exception:  the RENAME model of MULTIBAK
permits backups to appear in a directory different from the directory of the
original file, which the DOS command does not. Like the DOS "copy" command,
the COPY model of MULTIBAK permits backups to a different drive, while the
RENAME model, like the rename command in DOS, does not. Like the DOS "copy"
command, the COPY model of MULTIBAK keeps the original file intact, under its
original name; like the "rename" command, the RENAME model does not, since it
changes the file's name. On the other hand, long files can take considerably
longer to back up using the COPY model, although they can be RENAMEd in an
instant, and, in fact, as quickly as short files.


                           IV. How to Use MULTIBAK

In the following discussion, we will use the name MULTIBAK when we wish to
describe commands or features common to both the COPY model, MBC.EXE, and
the RENAME model, MBR.EXE.

At a DOS prompt (such as "C>") MULTIBAK is called as follows:

       C>MULTIBAK filespec [backup filename root] [max files]

(the arguments in square brackets, as usual, being optional).

"Filespec" refers to the specification of the file to be backed up. It can be
a "full" specification, including an optional drive and directory path.

The "backup filename root," if provided, over-rides the default filename for
backup files, which is described above (Section III). The rules for
constructing this argument are provided below, Section V.

"Max files," the final argument, specifies the maximum number of versions to
be saved. That value can be any number up to 99. If this optional argument is
provided, it over-rides the program default of 50. In case very large files
are saved when disk space is at a premium, it might be set as low as 2 or 3.
When plenty of disk space is available, or files are short and the recovery of
earlier versions might be critical, a value of 99 makes sense. Since the
program seeks the lowest integer available for a new backup by searching for
existing files starting at the maximum and proceeding down, an unnecessarily
large number might slightly slow execution. Note that "max files" can not be
entered unless an explicit "backup filename root" is also entered:  otherwise
the number entered as the maximum number of files will be taken as the file
name root.  For example, on its first execution

    MBC MYFILE 10

will produce a backup of MYFILE named "10.-1".

    MBC MYFILE MYFILE 10

will produce what is desired, a backup named "MYFILE.-1" searching only from
10 to 1 instead of from 50 to 1 for already existing backup files.

In all of the following examples, the file to be backed up is understood to be
C:\SUBDIR\MYFILE.EXT. MBC.EXE and MBR.EXE are either in the current default
directory or in the directory path. MULTIBAK means either MBC or MBR.

1. Succession of executions of COPY model, with default backup filenames.

Command                     Files existing after command executed.
-------                     --------------------------------------

C>MBC MYFILE.EXT              C:\SUBDIR\MYFILE.EXT
                              C:\SUBDIR\MYFILE.E1

C>MBC MYFILE.EXT              c:\subdir\MYFILE.EXT
                              c:\subdir\MYFILE.E1
                              c:\subdir\MYFILE.E2

                                    ******

2. Succession of executions of RENAME model, with default backup filenames.

Command                     Files existing after command executed.
-------                     --------------------------------------

C>MBR MYFILE.EXT              C:\SUBDIR\MYFILE.E1

C>MBR MYFILE.EXT              C:\SUBDIR\MYFILE.E1
                              C:\SUBDIR\MYFILE.E2

Note: Ordinarily, in this case, another program such as a word processor would
create a new version of MYFILE.EXT when MULTIBAK creates a backup.

                                    *****

3. Backup to a different directory.

Command                             Files existing after command executed.
-------                             --------------------------------------

C>MBC MYFILE.EXT \ALTDIR\MYFILE      C:\SUBDIR\MYFILE.EXT
                                     C:\ALTDIR\MYFILE.E1

                                      or

C>MBR MYFILE.EXT \ALTDIR\MYFILE      C:\ALTDIR\MYFILE.E1

                                    *****

4. Backup to a different drive.

Command                             Files existing after command executed.
-------                             --------------------------------------

C>MBC MYFILE.EXT D:\ANYDIR\MYFILE     C:\SUBDIR\MYFILE.EXT
                                      D:\ANYDIR\MYFILE.E1

                                    *****

5. Backup to a new backup filename.

Command                             Files existing after command executed.
-------                             --------------------------------------

C>MULTIBAK MYFILE.EXT BACKFILE        C:\SUBDIR\MYFILE.EXT
                                      C:\SUBDIR\BACKFILE.E1

                                    *****

5. Backup using the same filename, to a different drive and directory.

Command                             Files existing after command executed.
-------                             --------------------------------------

C>MBC MYFILE.EXT D:\ANYDIR\MYFILE     C:\SUBDIR\MYFILE.EXT
                                      D:\ANYDIR\MYFILE.E1

NOTE: In this example, the explicit filename MYFILE may NOT be omitted in
specifying the backup filename, even though it may be omitted when calling the
DOS COPY program.


                         V. The Backup Filename Root

The "backup filename root," if provided, over-rides the default filename for
backup files. It is called a "root" since an extension including a sequence
number is appended to it to construct the full backup filename.

The filename root:

     MUST include a first name for the backup file;
     MAY include a directory path;
     MUST NOT include an extension. If one is entered, it is ignored.

The extension will always be assigned by the program, by the rules described
above.

The rule on including a drive in the backup filename root differs for the COPY
and the RENAME models.

     You MAY include ANY drive when executing the COPY model.
     You MUST include the same drive if any is named in "filespec," i.e., the
        drive of the original file, when executing the RENAME model.

For example:

             C>MBR D:\SUBDIR\FILE.EXT D:\NEWDIR\BACKUP

is a correct command line entered from the current default disk C:, which
would rename the current version of FILE.EXT in directory \SUBDIR of
disk D: to one of BACKUP.E1, BACKUP.E2, BACKUP.E3, etc. (using the first
unused integer) in directory \NEWDIR of disk D:.

If the second "D:" is omitted,

             C>MBR D:\SUBDIR\FILE.EXT \NEWDIR\BACKUP

the command will be interpreted as an attempt to backup a file located on D:,
by renaming, to drive C:, the default drive, and the error message "Can not
back up to a different drive"  will appear on the screen. On the other hand,

             C>MBC D:\SUBDIR\FILE.EXT \NEWDIR\BACKUP

using the COPY version, will create the backup file demanded:
C:\NEWDIR\BACKUP.E?? where ?? represents a sequence number.


                               VI. PURGE

PURGE permits the deletion of selected generations of backup files created by
MULTIBAK. Particularly when files are long, storing many  generations could
use considerable disk space to little purpose.  But the chore of erasing large
numbers of backups might be  burdensome, since wild cards would probably wipe
out useful files, including the current version.  PURGE permits the user to
select the generations to be erased with a single command. On each execution
of MULTIBAK, the user is advised of the size in bytes and the serial number of
the new backup, so that he can use the purge facility when he feels the number
of backups is becoming excessive.

PURGE is called at the DOS prompt as follows:

       C>PURGE [filename] [highest sequence number] [starting sequence number]

where the "filename" is the name of the file whose backups are to be erased,
including an optional drive, directory, and extension. The "highest sequence
number" option permits erasing only the oldest generations, up to the
specified number. Thus, if a file has 12 generations of backup on disk it is
possible to erase, for example, the first six, or the first eleven. The second
argument to PURGE, the starting sequence number, permits still more
flexibility, the erasing of only the generations beginning at the number
entered.  Thus, if a file named "PROGRAM.C" has been backed up 8 times the
directory will show:

 PROGRAM.C1
 PROGRAM.C2
 PROGRAM.C3
 PROGRAM.C4
 PROGRAM.C5
 PROGRAM.C6
 PROGRAM.C7
 PROGRAM.C8

After execution of

     C:>PURGE PROGRAM.C 6 3

the disk will hold:

 PROGRAM.C1
 PROGRAM.C2
 PROGRAM.C7
 PROGRAM.C8

If, as in this case, the sequence is broken, C>PURGE PROGRAM.C will erase
files only until it finds a missing backup, i.e., in this case, it will erase
PROGRAM.C1 and PROGRAM.C2. If, however, an upper limit is given as an argument
to the command line all files up to that limit will be erased, regardless of
missing versions. Thus, all files in the broken list above will be deleted by
the command  C>PURGE PROGRAM.C 8.

These rules present an apparent danger to any file with an extension composed
exclusively of two digits. When MULTIBAK backs up a file called FILE.12 its
first backup will be called FILE.11, and its second backup will be called
FILE.13. (If FILE.12 exists, it will skip that name.) Now the original file,
FILE.12, appears to the computer as it does to a human observer as
indistinguishable from a backup, and the command PURGE FILE.12 would seem to
destroy the current version, FILE.12, along with its backups.  PURGE, however,
is programmed to avoid this;  it will never erase the current version entered
as its first argument on the command line.

Examples of the Use of PURGE
============================

                  Erasing all backup files:  PURGE MYFILE

Files existing before command       Files existing after command
=============================       ============================

 MYFILE.EXT                             MYFILE.EXT
 MYFILE.E1
 MYFILE.E2
 MYFILE.E3


          Erasing all backups except the most recent:   PURGE MYFILE 2

Files existing before command       Files existing after command
=============================       ============================

 MYFILE.EXT                             MYFILE.EXT
 MYFILE.E1                              MYFILE.E3
 MYFILE.E2
 MYFILE.E3


         Erasing all except the first two backups:  PURGE MYFILE 4 3

Files existing before command       Files existing after command
=============================       ============================

 MYFILE.EXT                             MYFILE.EXT
 MYFILE.E1                              MYFILE.E1
 MYFILE.E2                              MYFILE.E2
 MYFILE.E3
 MYFILE.E4


                 VII. Executing MULTIBAK from Other Programs

While MULTIBAK can be called from the DOS prompt like any other program, it is
specifically designed to be called from within applications that write
modifications to files and provide either a DOS command call facility or a DOS
Shell option.  For example, SPRINT is an editor that, like many others,
provides a macro, "call," that executes a DOS command.  The following macro
can be bound to a function key, so that it executes each time that key is
pressed:

        call MBR fname write fname

This stores the  current version of the file being edited (SPRINT calls it
"fname") without destroying previous backup versions, and then writes the
newly edited version to disk, under the original file name. This backup
procedure is very fast, and can be called a dozen times or more in a given
editing session, so as to provide the possibility of returning to many
different versions if desired. At the end of an editing session, some or all
of these backups can be PURGEd.

The popular word processor Word Perfect offers a different method of using
MULTIBAK while editing.  Instead of a macro for executing a DOS command,
Word Perfect offers a "shell" command. Pressing Control-F1, the user sees a
DOS prompt, which enables him to execute any DOS command including MBR or
MBC.


                               VIII. Disclaimer

Used properly, this software will perform as described. By using this
software, you acknowledge that this software may not suit your particular
requirements or be completely trouble-free. We are not responsible for your
specific application or any problems resulting from use of this software. We
have no liability to you or any other person or entity for any damage or loss,
including special, incidental, or consequential damages, caused by this
software, directly or indirectly.  Some states do not allow the limitation or
exclusion of liability for incidental or consequential damages, so the above
limitation or exclusion may not apply to you.